Thanks for the fix @capitanroy — this is a real bug and the overall approach (query IDs first, then batch) is solid. The getMaxObjectsInGet() helper follows existing patterns perfectly, and the PR description is excellent.

A few things to address before merging:

1. Redundant query in the single-batch path

When allIds.length <= maxBatchSize, the code re-issues the same ContactCard/query just to use the back-reference pattern. This means every contact load now costs 2 HTTP roundtrips instead of 1 — even for users with <500 contacts (the common case).

Since allIds is already available from the first query, the single-batch path can just pass the IDs directly:

if (allIds.length <= maxBatchSize) {
  const response = await this.request([
    ["ContactCard/get", { accountId, ids: allIds }, "0"],
  ], this.contactUsing());

  if (response.methodResponses?.[0]?.[0] === "ContactCard/get") {
    return (response.methodResponses[0][1].list || []) as ContactCard[];
  }
  return [];
}

2. Multi-batch: pack into a single JMAP request

Each batch currently issues a separate this.request() — N sequential HTTP roundtrips. RFC 8620 allows multiple method calls per request (up to maxCallsInRequest, default 50). All batches can be packed into one request:

const calls: [string, Record<string, unknown>, string][] = [];
for (let i = 0; i < allIds.length; i += maxBatchSize) {
  const batchIds = allIds.slice(i, i + maxBatchSize);
  calls.push(["ContactCard/get", { accountId, ids: batchIds }, String(calls.length)]);
}

const response = await this.request(calls, this.contactUsing());
const allContacts: ContactCard[] = [];
for (const [method, result] of response.methodResponses || []) {
  if (method === "ContactCard/get") {
    allContacts.push(...(result.list || []));
  }
}
return allContacts;

For 1200 contacts / 500 batch = 3 method calls — well within maxCallsInRequest, single roundtrip.

3. Tests need updating

The existing tests in jmap-contact-client.test.ts mock the old [query, get] two-method-in-one-request pattern. The new flow will break them. Please add/update tests covering:

• < maxObjectsInGet contacts (single-batch path)
• > maxObjectsInGet contacts (multi-batch path)
• 0 contacts
• Exact boundary (allIds.length === maxBatchSize)

4. Minor: limit: 1000 caps results silently (pre-existing)

Not introduced by this PR, but now more visible: the query has limit: 1000, so users with >1000 contacts will get a silently truncated list — the same class of issue this PR fixes. Worth a // TODO: paginate query for >1000 contacts comment so it doesn't get forgotten.

Happy to answer any questions. The core logic is right — just needs these adjustments and it's good to go.